<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<link href="Doc.css" rel="stylesheet"/>
<title>TreeGrid - Columns basics</title>
</head>
<body>
<div class="Doc">


<h1>Column basics</h1>
<p>TreeGrid documentation</p>

TreeGrid column is defined by tag &lt;<b>C</b>>, placed in &lt;Cols> or &lt;LeftCols> or &lt;RightCols> section.<br />
The column specifies <b>position</b>, <b>size</b>, <b>visibility</b> settings and restrictions of the grid column.<br /> 
And also specifies default type, formatting, editability and other cell setting for all cells in the column. The type, formatting and other settings can be overridden for every particular cell by its attributes.<br />
<i><b>Columns do not contain cell values</b>, the cells are defined in rows.</i><br />
<i>Column captions are defined in <b>Header</b> row(s).</i><br /><br />

TreeGrid column can be <b>fixed (frozen)</b> or <b>variable (scrollable)</b>.<br /><br />

<b>Fixed (frozen) column</b> can be positioned on the left or on the right grid side. The fixed column cannot be scrolled outside view.<br />
To set fixed column, place the &lt;<b>C</b>> tag to &lt;<b>LeftCols</b>> or &lt;<b>RightCols</b>> section.<br />
<i>If all fixed columns together are too wide, wider then <a href="Create.htm#Creating">main tag</a> width, TreeGrid can neither scroll them nor display them, so it cannot display its content and displays only message "Too small extents".</i><br /><br />

<i><b>Variable (scrollable) column</b></i> is positioned between left and right fixed section.<br /> 
To set variable column, place the &lt;<b>C</b>> tag to &lt;<b>Cols</b>> section.<br />
<i>If all variable columns are wider then the variable section, they are horizontally scrolled.</i><br />

A user can move the column between section (freeze / unfreeze) by mouse dragging if the column have set <a href="ColPosition.htm#CCanMove">CanMove</a>='2' (it is set by default).<br /><br />

To predefine some attributes for more columns define &lt;<b>D</b>> tag with these attributes and place it to &lt;<b>DefCols</b>> section. And point the specified columns to it by their <a href="#CDef">Def</a> attribute.<br />
To predefine some attributes for all columns, set them to <tt>&lt;<b>D Name='C'</b>></tt> tag. This tag is placed also to &lt;<b>DefCols</b>> section. By default it is defined in Defaults.xml with default settings for all grids.<br />
For example if you define <tt>&lt;Def>&lt;D Name='C' Type='Int'/>&lt;/Def></tt> all columns will have Type Int.<br /><br />

There is one special column, the row's <b>left panel</b> with buttons for deleting and selecting row. It is positioned as the first left fixed column and can be visible or hidden. It can be set by &lt;<b>Panel</b>> attribute placed in root &lt;Grid> tag.<br /><br />

In tree there is one main column where is displayed tree with icons for expanding and collapsing. In grid there can be only one main column, its name is set by <tt>&lt;Cfg <a href="Tree.htm#CfgMainCol">MainCol</a>></tt> attribute.<br /><br />

Column caption and other header setting are set by &lt;<b>Header</b>> tag placed in root &lt;Grid> tag.<br />

<!-- Name -->
<a name="CName"></a>
<div class="XML">
   <u></u> <b>&lt;C></b> <i>string</i>
   <h4>Name</h4> <s></s>
</div>
Column name. <b>Required</b>. Every column must have set this attribute.<br /> 
The Name identifies column and row's cells. Under this name are row's cells in this column set and accessed.<br /> 
All column names must be unique among all column names inside one grid.<br /> 
Under this name grid saves column configuration to the cookies.<br />
In JavaScript API, cell is accessed by column name.<br />
Column names are used also in formulas.<br />
<b style="color:red;">!</b> <b>Attention</b> <b style="color:red;">!</b><br />
<div class="L1"><i>
Column names are case sensitive.<br />
Column names can contain only letters (a-z, A-Z), underscore '_' and digits (0-9), but cannot start with digit and should not start with underscore.<br />
Column names must not interfere with row's attribute names, like Def, Kind or Deleted !<br /> 
</i></div> 
The best way is to name columns as letter 'A', 'B' or 'a', 'b'. There is no interference and data length is short.<br />
For grids with many columns and saved configuration to cookies the column names should be less then 4 characters long, to shorten cookie length.<br />

<!-- value -->
<a name="HeaderCellvalue"></a>
<div class="XML">
   <u></u> <b style="width:110px;">&lt;Header cell></b> <i>string</i>
   <h4>value</h4> <s></s>
</div>
Column <b>caption</b> is <u>not</u> set in &lt;C> tag, but in &lt;<b>Header</b>> row cell.<br />
The &lt;Header> row is fixed (Head or Foot) row with column captions and sorting icons. It cannot be editable.<br />
It has the same row and cell attributes like normal grid row, but it have usually different look (according to style definition).<br />
You can especially use Header style attribute like <a href="CellStyle.htm#CAlign">Align</a>, <a href="CellStyle.htm#CWrap">Wrap</a> or <a href="CellStyle.htm#HeaderNoEscape">NoEscape</a> to format the column captions.<br />
You can have <b>more Header rows</b> in grid. You can also span the Header cells to show merged column captions.<br />

<!-- ShowColNames -->
<a name="IShowColNames"></a>
<div class="XML">
   <u>new <b>12.0</b></u> <b>&lt;I></b> <i>bool</i>
   <h4>ShowColNames</h4> <s>[0/1]</s>
</div>
If the fixed row cells show column names. By default it is set to 1 for Header rows and 0 for all others.<br />

<!-- MenuName -->
<a name="CMenuName"></a>
<div class="XML">
   <u></u> <b>&lt;C></b> <i>string</i>
   <h4>MenuName</h4> <s></s>
</div>
Html string displayed in Columns menu for this column. If not set, the column caption is displayed.

<!-- SearchNames -->
<a name="CSearchNames"></a>
<div class="XML">
   <u></u> <b>&lt;C></b> <i>string []</i>
   <h4>SearchNames</h4> <s></s>
</div>
Comma separated strings as possible names of the column. Used for search and editable formulas.<br />

<!-- Def -->
<a name="CDef"></a>
<div class="XML">
   <u>new <b>6.0</b> <i>upd <b>10.0</b></i></u> <b>&lt;C> &lt;D></b> <i>string</i>
   <h4>Def</h4> <s>["C"]</s>
</div>
The name of default column &lt;<b>D</b>> used for this column or default column. From this default the column inherits all its <u>not set</u> attribute values.<br />
<i>Remember, opposite to default rows all the columns read their values from default columns <u>on start</u>! So the default columns are <u>not</u> accessible by API.</i><br />
Default value for Gantt type column is "Gantt", for other columns "C".<br />
<i>Since 10.0.</i> It can contain more default names, comma separated. <i>Remember the difference, <tt>&lt;I Def/></tt> can contain only one default.</i><br />

<!-- Def Name -->
<a name="DNameC"></a>
<div class="XML">
   <u><i>upd <b>6.0</b></i></u> <b>&lt;D></b> <i>string</i>
   <h4>Name</h4> <s></s>
</div>
Name of default column. Required. This name is referenced by column attribute <a href="#CDef">Def</a>.<br />
The &lt;D> tag as default column can be placed only to &lt;<b>DefCols</b>> section.<br />
Any custom name can be used for default row.<br />
There is one predefined name "<b style="color:blue;">C</b>" as default column for all columns in grid.<br />

<!-----------------------------------------------------------------------  Suggest list (auto complete) ------------------------------------------------->
<a name="ColIndex"></a>
<h2>Column index</h2>
Shows row with column positions, usually as number from 1 or alphabetical name.<br />
<i>It does <u>not</u> identify column uniquely, for column identification use column <a href="#CName">Name</a> instead.</i><br />
Used also for <a href="CellEditFormula.htm">editable formulas</a>. See also <a href="RowBasics.htm#RowIndex">row index</a>.<br />

<!-- ColIndex -->
<a name="CfgColIndex"></a>
<div class="XML">
   <u>new <b>12.0</b></u> <b>&lt;Cfg></b> <i>string</i>
   <h4>ColIndex</h4> <s></s>
</div>
An id of the row that will show the column positions in grid.<br />
If the row does not exist, it is created as the last row in Head section as &lt;Header Def="Header" id=<i>ColIndex</i> Visible="1" Kind="Header"/>.<br />
It is possible to set SearchNames to the same value as ColIndex to use the col index as column name.<br />
<i>I does not work in server paging.</i><br />
<i>It iterates all the ColIndex cells after any column order change and resets the value, so it can be slow in very large grids.</i><br />

<!-- ColIndexType -->
<a name="CfgColIndexType"></a>
<div class="XML">
   <u>new <b>12.0</b> <i>upd <b>13.0</b></i></u> <b>&lt;Cfg></b> <i>int</i>
   <h4>ColIndexType</h4> <s>[0]</s>
</div>
Bit array of flags for the <a href="#CfgColIndex">ColIndex</a>.<br />
<table>
   <tr><td style="width:70px;">1.bit (<b>&amp;1</b>)</td><td>Count also deleted columns</td></tr>
   <tr><td>2.bit (<b>&amp;2</b>)</td><td>Count also filtered columns <i>not implemented yet</i></td></tr>
   <tr><td>3.bit (<b>&amp;4</b>)</td><td>Count also manually hidden columns</td></tr>
   <tr><td>4.bit (<b>&amp;8</b>)</td><td>Count also left section columns</td></tr>
   <tr><td>5.bit (<b>&amp;16</b>)</td><td>Count also right section columns</td></tr>
   <tr><td>6.bit (<b>&amp;32</b>)</td><td>Count also Panel and Gantt type columns and <i>(since 13.0)</i> <a href="RowBasics.htm#CfgRowIndex">RowIndex</a> column</td></tr>
</table>
If loading <b>xlsx</b> file, ColIndex is automatically set to <b>30</b> = 2+4+8+16. Or to <b>31</b> if ColIndexType contained bit 1.<br />

<!-- ColIndexStart -->
<a name="CfgColIndexStart"></a>
<div class="XML">
   <u>new <b>12.0</b></u> <b>&lt;Cfg></b> <i>int</i>
   <h4>ColIndexStart</h4> <s>[1]</s>
</div>
The index is created from this number. Useful to have all indexes the same length (e.g. starting from 1000). 

<!-- ColIndexChars -->
<a name="CfgColIndexChars"></a>
<div class="XML">
   <u>new <b>12.0</b></u> <b>&lt;Cfg></b> <i>string</i>
   <h4>ColIndexChars</h4> <s>[]</s>
</div>
Characters to build the index. By default the index is a number. Setting the ColIndexChars="ABCDEFGHIJKLMNOPQRSTUVWXYZ" use alphabetical indexes.

<!-- AutoCols -->
<a name="CfgAutoCols"></a>
<div class="XML">
   <u>new <b>12.0</b></u> <b>&lt;Cfg></b> <i>int</i>
   <h4>AutoCols</h4> <s>[0]</s>
</div>
If set, automatically generates given number of columns. Used only when <a href="#CfgColIndex">ColIndex</a> is set.<br />
The columns are generated as last columns in middle section.<br />
The column gets its <a href="#CName">Name</a> as its generated index.
If the index is a number, the Name gets "C" prefix, like C256.
The column gets its <a href="#CDef">Def</a> = "Auto".<br />
See also <a href="ColPaging.htm#CfgAutoColPages">AutoColPages</a> to add new columns on scroll right.<br />

<!-- AutoWidths -->
<a name="CfgAutoWidths"></a>
<div class="XML">
   <u>new <b>13.0</b></u> <b>&lt;Cfg></b> <i>int[]</i>
   <h4>AutoWidths</h4> <s></s>
</div>
A comma separated list of widths for individual columns created by AutoCols.<br />
If the individual item is set to "0", the column is hidden. If the individual item is empty or not set, it is used default width.<br />

<!-- NoIndex -->
<a name="CNoIndex"></a>
<div class="XML">
   <u>new <b>12.0</b></u> <b>&lt;C></b> <i>bool</i>
   <h4>NoIndex</h4> <s>[0]</s>
</div>
If set to 1, the column will not be counted by <a href="#CfgColIndex">ColIndex</a>.

<!-- HasIndex -->
<a name="HasIndex"></a>
<a name="TColvariableHasIndex"></a>
<div class="API">
   <u>new <b>12.0</b></u> <b>TCol variable</b> <i>int</i>
   <h4>HasIndex</h4> <s>[0]</s>
</div>
Column position from 1 or 0 for column without index. On grid loading it is available in OnReady and later.
It is not affected by ColIndexStart / ColIndexChars. Accessible as grid.Cols[col].HasIndex.

<!-- GetColByIndex -->
<a name="GetColByIndex"></a>
<div class="API">
   <u>new <b>12.0</b></u> <b>API method</b> <i>string</i>
   <h4>GetColByIndex</h4> <s>(<i>type</i> <b>index</b>, <i>bool</i> type = 0)</s>
</div>
Returns column name according to its index. On grid loading it is available in OnReady and later.<br />
For <i>type</i> = <b>0</b> The <b>index</b> is number from 1 as for column (<a href="#HasIndex">HasIndex</a>). <br />
For <i>type</i> = <b>1</b> The <b>index</b> is number or string according to the displayed column index in <a href="#CfgColIndex">ColIndex</a> row. <br />

<!-- GetColIndex -->
<a name="GetColIndex"></a>
<div class="API">
   <u>new <b>12.0</b></u> <b>API method</b> <i>type</i>
   <h4>GetColIndex</h4> <s>(<i>string</i> <b>col</b>, <i>bool</i> <b>type</b> = 0, <i>type</i> <b>default</b> = null)</s>
</div>
Returns column index according to its name. On grid loading it is available in OnReady and later.<br />
For <i>type</i> = <b>0</b> Returns number from 1 as the column (<a href="#HasIndex">HasIndex</a>). <br />
For <i>type</i> = <b>1</b> Returns number or string as the displayed column index in <a href="#CfgColIndex">ColIndex</a> row. <br />
If the column has not index, returns <b>default</b>.


<!-- OnColIndex -->
<a name="OnColIndex"></a>
<div class="API">
   <u>new <b>12.0</b></u> <b>API event</b> <i>bool</i>
   <h4>OnColIndex</h4> <s>(<i>TGrid</i> <b>grid</b>, <i>string[]</i> <b>values</b>)</s>
</div>
Called on recalculate the <a href="#CfgColIndex">ColIndex</a> column.
<b>values</b> contains the changed indexes that will be assigned after the event finishes. It is named array as new value by column name. The indexes are always from 1, the index to delete is set as "".<br />
You can modify the <b>values</b>, but you cannot add or delete the items from the array.<br />
Or you can assign your own index to the ColIndex column and true to not process the values, it is not possible if the index is used for calculated formula.


</div>
</body>	
</html>